react-linear-feedback 0.1.1 → 0.3.0

package/README.md

@@ -2,34 +2,42 @@
 
 [![npm version](https://img.shields.io/npm/v/react-linear-feedback.svg)](https://www.npmjs.com/package/react-linear-feedback) [![license](https://img.shields.io/npm/l/react-linear-feedback.svg)](./LICENSE)
 
-**A drop-in React feedback widget that turns a drawn box + note into a Linear issue with an annotated screenshot.**
+**A drop-in feedback widget that turns a drawn box + note into a Linear issue with an annotated screenshot.** Use it as a React component, or embed it on **any site** — Framer, Webflow, plain HTML — with a single script tag.
 
-A trusted user opens it with `?feedback`, **drags a box** over the page, picks a type (**Bug / Improvement**), writes a note — and it captures a screenshot and files a Linear issue. Framework-agnostic, self-contained styling, no design system required.
+A user opens the widget, **drags a box** over the page, picks a type (**Bug / Improvement**), writes a note — and it captures a screenshot and files a Linear issue. Self-contained styling, no design system required.
 
 <!-- Demo: record a short GIF and drop it here → ![demo](docs/demo.gif) -->
 > _Draw a box anywhere → type a note → it lands in Linear with the annotated screenshot and page context._
 
+- 🌍 **Three ways in** — a React component, a framework-agnostic `init()` import for any bundler app, or a ~23KB script tag for sites with no build step
 - 🪶 **Themeable in one prop** — no CSS import, no Tailwind, no design system; styles are injected at runtime
-- 🌍 **Works in any React app** — Next.js, Vite, Remix, CRA… (no `next` dependency; `"use client"` is built in)
 - 🖼️ **Annotated screenshots** via [`modern-screenshot`](https://github.com/qq15725/modern-screenshot) (handles Tailwind v4 / `oklch()`)
-- 🏷️ **Labels by name, self-healing** — resolved at request time, so recoloring/recreating a label in Linear won't break it; applied best-effort
-- 🔌 **Tiny server core** + Next.js & Node/Express adapters
+- 🏷️ **Labels by name, self-healing** — resolved at request time (and cached), so recoloring/recreating a label in Linear won't break it; applied best-effort
+- 🔌 **One Web-standard server handler** + Next.js, Node/Express, and Vite-dev adapters, with built-in CORS for cross-origin embeds
 
 ## Contents
 
-- [Install](#install) · [Quick start (Next.js)](#quick-start-nextjs) · [Vite / any backend](#use-with-vite--any-react-app) · [Linear setup](#linear-setup) · [Configuration](#configuration) · [Theming](#theming) · [Custom types](#custom-types) · [Security](#security) · [Troubleshooting](#troubleshooting) · [License](#license)
+- [How it fits together](#how-it-fits-together) · [React apps (npm)](#react-apps-npm) · [Any framework (npm import)](#any-framework-npm-import) · [Any site (script tag)](#any-site-script-tag) · [The server handler](#the-server-handler) · [Linear setup](#linear-setup) · [Configuration](#configuration) · [Theming](#theming) · [Custom types](#custom-types) · [Security](#security) · [Troubleshooting](#troubleshooting) · [License](#license)
 
-## Install
+## How it fits together
+
+The widget (React component or script-tag embed) never talks to Linear directly — it POSTs to **your** endpoint, which holds the API key server-side and creates the issue:
+
+```
+widget (browser) ──POST──▶ your endpoint (createWebHandler) ──▶ Linear API
+```
+
+So every setup is two steps: mount the widget, and deploy the handler ([The server handler](#the-server-handler)).
+
+## React apps (npm)
 
 ```bash
 npm i react-linear-feedback
-# the server entry needs the Linear SDK (optional peer):
-npm i @linear/sdk
 ```
 
-`react` / `react-dom` are peer dependencies. `@linear/sdk` is an **optional** peer — only needed wherever you run the server handler. Do [Linear setup](#linear-setup) first to get your API key, team, and labels.
+`react` / `react-dom` are peer dependencies. `@linear/sdk` ships as a dependency — it's imported only by the server entry, so it's tree-shaken out of client bundles.
 
-## Quick start (Next.js, App Router)
+### Next.js (App Router)
 
 **1. Server route** — `app/api/feedback/route.ts`:
 
@@ -62,38 +70,169 @@ export default function RootLayout({ children }) {
 
 No `"use client"` needed — the package ships it, so you can mount `<FeedbackGate>` straight from a Server Component layout.
 
-**3. Turn it on.** The widget is **hidden by default**. Visit any page with **`?feedback`** (or `?feedback=1`) to enable it; a cookie remembers the choice for 90 days. `?feedback=0` turns it off.
+**3. Turn it on.** `<FeedbackGate>` is **hidden by default**. Visit any page with **`?feedback`** (or `?feedback=1`) to enable it; a cookie remembers the choice for 90 days. `?feedback=0` turns it off. (Use `<FeedbackWidget>` instead for an always-visible button.)
 
-## Use with Vite / any React app
+### Vite SPA
 
-Mount the widget and point it at your backend:
+Mount the widget the same way; the handler runs as a serverless function in production and as a dev-server plugin locally:
 
 ```tsx
 import { FeedbackGate } from "react-linear-feedback/react";
 
-<FeedbackGate endpoint="https://api.example.com/feedback" brandColor="#7f56d9" />
+<FeedbackGate brandColor="#7f56d9" />; // endpoint defaults to /api/feedback (same origin)
+```
+
+**Production — a Vercel serverless function** at `api/feedback.ts`:
+
+```ts
+import { createNodeHandler, cookieGate } from "react-linear-feedback/server";
+
+export default createNodeHandler({
+  apiKey: process.env.LINEAR_API_KEY!,
+  teamId: process.env.LINEAR_TEAM_ID!,
+  authorize: cookieGate("wh_feedback"),
+});
+```
+
+Set `LINEAR_API_KEY` / `LINEAR_TEAM_ID` in your Vercel project's env (server-side — **not** `VITE_`-prefixed, so they never reach the bundle).
+
+**Local dev — the Vite plugin**, so `vite dev` serves the same endpoint (without it, `POST /api/feedback` 404s locally):
+
+```ts
+// vite.config.ts
+import { defineConfig, loadEnv } from "vite";
+import { linearFeedback } from "react-linear-feedback/vite";
+import { cookieGate } from "react-linear-feedback/server";
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), ""); // reads .env (LINEAR_* are server-side, un-prefixed)
+  return {
+    plugins: [
+      linearFeedback({
+        apiKey: env.LINEAR_API_KEY,
+        teamId: env.LINEAR_TEAM_ID,
+        authorize: cookieGate("wh_feedback"),
+      }),
+    ],
+  };
+});
+```
+
+The plugin is dev-only (`apply: "serve"`) — it has no effect on the production build.
+
+## Any framework (npm import)
+
+Not a React app? The same self-mounting widget is available as a plain ESM import — Vue, Svelte, Astro, Solid, vanilla TS, anything with a bundler. **Zero peer dependencies** (a compact React-compatible runtime is bundled inside, ~23KB gz):
+
+```ts
+import { init, destroy } from "react-linear-feedback/embed";
+
+init({
+  endpoint: "/api/feedback",
+  brandColor: "#7f56d9",
+  // mode: "gated",          // ?feedback URL-param gate, like <FeedbackGate>
+  // token: "...",           // for headerGate'd cross-origin endpoints
+});
+
+// destroy() unmounts it (e.g. SPA route teardown / HMR)
+```
+
+`init()` takes the same options as the React component plus `mode` and `token` (see [Configuration](#configuration)). Calling it again replaces the existing instance.
+
+React apps should prefer the [`<FeedbackGate>` component](#react-apps-npm) — it shares the page's React instead of shipping a second renderer.
+
+## Any site (script tag)
+
+No npm, no build step, no React on the page — the embed bundle (~23KB gz, served from a CDN off the npm package) mounts the same widget on any site: Framer, Webflow, WordPress, plain HTML.
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/react-linear-feedback@0.3.0/dist/embed/linear-feedback.js"
+  data-endpoint="https://your-app.example.com/api/feedback"
+  data-brand-color="#7f56d9"
+  data-token="your-embed-token"
+  defer
+></script>
+```
+
+Pin the version in the URL (as above). Because the page and the endpoint are usually on **different origins**, the handler needs `allowedOrigins` set — see [The server handler](#the-server-handler).
+
+It must be a classic `<script src>` tag (not `type="module"`, not injected via `innerHTML`) so the embed can read its own config; if you need dynamic injection, use `data-manual` + `init()` below.
+
+### Script-tag options
+
+| Attribute | Maps to | Notes |
+| --- | --- | --- |
+| `data-endpoint` | `endpoint` | **Required in practice** — your deployed handler URL |
+| `data-brand-color` | `brandColor` | Any CSS color |
+| `data-position` | `position` | `bottom-right` (default) \| `bottom-left` \| `top-right` \| `top-left` \| `right` \| `left` |
+| `data-fab-label` | `fabLabel` | Button text |
+| `data-mode` | `mode` | `open` (default, always visible) \| `gated` (`?feedback` URL param + cookie, like `<FeedbackGate>`) |
+| `data-token` | `token` | Sent as the `x-feedback-token` header — pair with `headerGate` on the server |
+| `data-z-index` | `zIndex` | Override the widget's stacking context |
+| `data-name-required` | `nameRequired` | `"false"` to skip the name prompt |
+| `data-manual` | — | `"true"` disables auto-init; call `LinearFeedback.init()` yourself |
+
+### JS API
+
+Options that aren't expressible as data attributes (like custom `types`) go through `window.lfbConfig` (set **before** the script tag; merged over the data attributes) or the imperative API:
+
+```html
+<script>
+  window.lfbConfig = {
+    types: [
+      { id: "bug", label: "Bug", color: "#ef4444", icon: "bug" },
+      { id: "idea", label: "Idea", color: "#22c55e", icon: "improvement" },
+    ],
+  };
+</script>
+<script src="https://cdn.jsdelivr.net/npm/react-linear-feedback@0.3.0/dist/embed/linear-feedback.js" data-endpoint="..." defer></script>
+```
+
+```js
+// With data-manual="true":
+LinearFeedback.init({ endpoint: "https://...", brandColor: "#7f56d9", token: "..." });
+LinearFeedback.destroy();
 ```
 
-Run the handler on any Node server (Express shown):
+A runnable demo lives in [`examples/embed.html`](./examples/embed.html) + [`examples/dev-server.mjs`](./examples/dev-server.mjs).
+
+## The server handler
+
+`createWebHandler` is the canonical handler — a Web-standard `(Request) => Promise<Response>` function. `createNextRoute` is the same function under its Next.js name, and `createNodeHandler` wraps it for `(req, res)`-style servers (Express, plain `node:http`, Vercel Node functions). All of them run on the **Node runtime** (the screenshot upload uses `Buffer`; Edge isn't supported).
+
+```ts
+import { createWebHandler, headerGate } from "react-linear-feedback/server";
+
+const handler = createWebHandler({
+  apiKey: process.env.LINEAR_API_KEY!,
+  teamId: process.env.LINEAR_TEAM_ID!,
+  // Required for script-tag embeds on other domains — enables CORS (preflight + headers):
+  allowedOrigins: ["https://your-marketing-site.com", "https://www.your-marketing-site.com"],
+  // Cookie gates can't cross origins — gate embeds with the shared token instead:
+  authorize: headerGate("your-embed-token"),
+});
+```
+
+Cross-origin example end-to-end: the script tag on `your-marketing-site.com` has `data-endpoint="https://your-app.example.com/api/feedback"` and `data-token="your-embed-token"`; the handler at that endpoint lists the marketing origin in `allowedOrigins` and gates with `headerGate("your-embed-token")`. Same-origin setups (widget and handler on one domain) need neither.
+
+### Express / other Node servers
+
+`createNodeHandler` works with or without `express.json()`:
 
 ```ts
 import express from "express";
-import cors from "cors";
 import { createNodeHandler, cookieGate } from "react-linear-feedback/server";
 
 const app = express();
-// If the app and API are on different origins, CORS is required or the fetch is blocked:
-app.use("/feedback", cors({ origin: "https://your-site.com", credentials: true }));
-app.post("/feedback", createNodeHandler({
+app.post("/api/feedback", createNodeHandler({
   apiKey: process.env.LINEAR_API_KEY!,
   teamId: process.env.LINEAR_TEAM_ID!,
-  authorize: cookieGate("wh_feedback"), // optional — omit to leave the endpoint open
+  authorize: cookieGate("wh_feedback"),
 }));
 app.listen(8787);
 ```
 
-The handler reads the raw body itself, so it works with or without `express.json()`.
-
 ## Linear setup
 
 You need three things from Linear:
@@ -110,7 +249,7 @@ LINEAR_TEAM_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
 ## Configuration
 
-### Widget props (`<FeedbackGate>` / `<FeedbackWidget>`)
+### Widget props (`<FeedbackGate>` / `<FeedbackWidget>` / `LinearFeedback.init`)
 
 Most apps only set `brandColor` and maybe `endpoint`.
 
@@ -118,32 +257,35 @@ Most apps only set `brandColor` and maybe `endpoint`.
 | --- | --- | --- |
 | `endpoint` | `/api/feedback` | Where the widget POSTs |
 | `brandColor` | `#6366f1` | FAB / active / focus color (sets the `--lfb-brand` CSS var) |
-| `position` | `bottom-right` | `bottom-right` \| `bottom-left` \| `top-right` \| `top-left` |
+| `position` | `bottom-right` | `bottom-right` \| `bottom-left` \| `top-right` \| `top-left` \| `right` \| `left` (edge tabs: compact icon-only launcher) |
 | `types` | Bug, Improvement | `{ id, label, color, icon? }[]` shown in the composer |
 | `nameRequired` | `true` | Ask for a reporter name before the first submission (saved to localStorage, included in the issue) |
 | `nameStorageKey` | `wh_feedback_name` | localStorage key for the remembered name |
 | `fabLabel` | `Give feedback` | Floating button text |
+| `zIndex` | `2147483640` | Stacking context for the widget's layers (sugar for `--lfb-z`, see [Theming](#theming)) |
+| `requestHeaders` | — | Extra headers sent with the submission (the embed's `token` uses this) |
 | `urlParam` ¹ | `feedback` | Toggle param |
 | `cookieName` ¹ | `wh_feedback` | Enabled-state cookie name |
 | `cookieValue` ¹ | `1` | Cookie value when enabled |
 | `cookieMaxAgeSeconds` ¹ | `7776000` (90d) | Cookie lifetime |
 
-¹ `<FeedbackGate>` only.
+¹ `<FeedbackGate>` only (and the embed's `mode: "gated"`).
 
-### Server config (`createNextRoute` / `createNodeHandler` / `createFeedbackIssue`)
+### Server config (`createWebHandler` / `createNextRoute` / `createNodeHandler` / `createFeedbackIssue`)
 
 | Field | Description |
 | --- | --- |
 | `apiKey` | Linear personal API key (**server-side only**) |
 | `teamId` | Target team UUID |
 | `labels` | Optional `{ [typeId]: labelName }` map. Default: the type id **is** the label name (so type `bug` → label `bug`) |
-| `allowedOrigin` | Optional single-origin allowlist (adapters) |
-| `authorize(req)` | Optional gate; return `false` to reject. `cookieGate(name, value="1")` is provided |
+| `labelCacheTtlMs` | How long label name→ID lookups are cached (default 10 min; `0` disables). Saves a Linear API round-trip per submission |
+| `allowedOrigins` | Origins allowed to call the endpoint cross-origin (exact origins or `"*"`); enables CORS. Required for script-tag embeds on other domains |
+| `authorize(req)` | Optional gate; return `false` to reject. `cookieGate(name, value="1")` and `headerGate(token, headerName="x-feedback-token")` are provided |
 
 Remap type ids to differently-named Linear labels:
 
 ```ts
-createNextRoute({
+createWebHandler({
   apiKey, teamId,
   labels: { bug: "bug", idea: "feature-request" },
 });
@@ -151,9 +293,15 @@ createNextRoute({
 
 ## Theming
 
-Set `brandColor`, or override any CSS variable on `.lfb-doc-layer, .lfb-fixed-layer`:
+Set `brandColor`, or override any CSS variable on `.lfb-root`:
 `--lfb-brand`, `--lfb-fg`, `--lfb-surface`, `--lfb-border`, `--lfb-radius`, `--lfb-rect`, `--lfb-z`, `--lfb-font`.
 
+The widget defaults to a very high `--lfb-z` (`2147483640`) so it sits above app chrome. If it lands on top of your own modals or toasts, lower it — either with the `zIndex` prop / `data-z-index` attribute, or in CSS:
+
+```css
+.lfb-root { --lfb-z: 40; }
+```
+
 ## Custom types
 
 ```tsx
@@ -165,25 +313,31 @@ Set `brandColor`, or override any CSS variable on `.lfb-doc-layer, .lfb-fixed-la
 />
 ```
 
-Each `type.id` is matched to a Linear label of the same name. If your label is named differently, map it on the server via `labels` (above). Built-in `icon` values: `"bug"`, `"improvement"`, `"dot"`.
+Each `type.id` is matched to a Linear label of the same name. If your label is named differently, map it on the server via `labels` (above). Built-in `icon` values: `"bug"`, `"improvement"`, `"dot"`. For the script-tag embed, pass `types` via `window.lfbConfig` or `LinearFeedback.init()`.
 
 ## Security
 
 ⚠️ **The endpoint creates Linear issues**, so it's effectively write access to your tracker, and it's **open by default**. Before shipping on a public page:
 
-- **Gate it** with `authorize` (e.g. `cookieGate`, or your own session check).
-- **Restrict origin** with `allowedOrigin: "https://your-site.com"`.
+- **Gate it** with `authorize` (e.g. `cookieGate`, `headerGate`, or your own session check).
+- **Restrict origins** with `allowedOrigins: ["https://your-site.com"]`.
 - **Rate-limit** if the page is public (e.g. per-IP).
 
+### Gating an embedded (cross-origin) widget
+
+`cookieGate` only works **same-origin**: the gate cookie is written on the page's origin, so the browser never sends it with a cross-origin submission. For script-tag embeds, use the shared token instead — `data-token="..."` on the script tag plus `authorize: headerGate("...")` on the handler. The token is visible in the page source, so treat it as a **tripwire against drive-by spam, not authentication**; combine it with `allowedOrigins` and rate limiting.
+
 Your `LINEAR_API_KEY` stays server-side; the package never ships it to the browser. Screenshots are uploaded to Linear's **private** asset storage — they render inside the issue, but the URL needs a fresh signed token to fetch elsewhere (it can't be hot-linked). If a screenshot upload fails, the issue is still created without it.
 
 ## Troubleshooting
 
 Submissions never throw in the UI — failures are logged to the browser console with a `[feedback]` prefix, and server errors return a JSON `message`. If issues aren't being created, check:
 
-- `endpoint` points at your route, and `LINEAR_API_KEY` / `LINEAR_TEAM_ID` are set.
-- **CORS** is configured when the app and API are on different origins.
+- `endpoint` points at your route, and `LINEAR_API_KEY` / `LINEAR_TEAM_ID` are set (the handler logs a `[feedback]` warning at startup when they're missing).
+- A rejected `authorize` returns **404 by design** — the endpoint is hidden, not just forbidden. If you're debugging your gate and seeing 404s, it's not a routing problem.
+- **CORS**: cross-origin pages (script-tag embeds) need their origin in `allowedOrigins`, and the browser must reach the endpoint with both `OPTIONS` and `POST`.
 - `runtime = "nodejs"` is set on the Next.js route (Edge has no `Buffer`).
+- On a **Vite SPA**, `POST /api/feedback` 404s under `vite dev` unless you add the [`linearFeedback` Vite plugin](#vite-spa) (or run `vercel dev`). In production it's served by your deployed function.
 - The expected Linear **labels exist** (otherwise the issue is created without a label, with a warning).
 
 ## License

package/dist/embed/index.d.ts

@@ -0,0 +1,48 @@
+/** Built-in inline icon keys usable on a type option. */
+type FeedbackIconName = "bug" | "improvement" | "dot";
+/** A selectable issue type shown in the composer's segmented control. */
+type FeedbackTypeOption = {
+    /** Stable id sent to the server and mapped to a Linear label name. */
+    id: string;
+    /** Human label shown in the UI and used in the issue title (e.g. "Bug"). */
+    label: string;
+    /** Swatch background color, any CSS color. */
+    color: string;
+    /** Optional built-in icon for the swatch. */
+    icon?: FeedbackIconName;
+};
+
+type FeedbackPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left"
+/** Edge tabs: compact, icon-only launcher flush to the side, vertically centered. */
+ | "right" | "left";
+type FeedbackWidgetProps = {
+    /** Endpoint that runs the server handler (default "/api/feedback"). */
+    endpoint?: string;
+    /** Brand color for the FAB, active states and focus rings (any CSS color). */
+    brandColor?: string;
+    /** Corner for the floating button (default "bottom-right"). */
+    position?: FeedbackPosition;
+    /** Selectable issue types (default Bug / Improvement). */
+    types?: FeedbackTypeOption[];
+    /** Ask for a reporter name before the first submission (default true). */
+    nameRequired?: boolean;
+    /** localStorage key for the remembered name. */
+    nameStorageKey?: string;
+    /** Label on the floating button (default "Give feedback"). */
+    fabLabel?: string;
+    /** Stacking context for the widget's layers — sugar for the `--lfb-z` CSS variable. */
+    zIndex?: number;
+    /** Extra headers sent with the submission (e.g. x-feedback-token for `headerGate`). */
+    requestHeaders?: Record<string, string>;
+};
+
+type LinearFeedbackConfig = FeedbackWidgetProps & {
+    /** "open" (default): widget always visible. "gated": enabled via ?feedback URL param + cookie. */
+    mode?: "open" | "gated";
+    /** Shared secret sent as the x-feedback-token header — pair with `headerGate` on the server. */
+    token?: string;
+};
+declare function init(config?: LinearFeedbackConfig): void;
+declare function destroy(): void;
+
+export { type LinearFeedbackConfig, destroy, init };